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The  Durra  Application  Debugger/Monitor 


Abstract.  '•Durra  is  a  language  designed  to  support  the  construction  of  distri¬ 
buted  applications  using  concurrent,  coarse-grained  tasks  running  on  net¬ 
works  of  heterogeneous  processors.  An  application  written  in  Durra  describes 
the  tasks  to  be  instantiated  and  executed  as  concurrent  processes,  the  types 
of  data  tc  be  exchanged  by  the  processes,  and  the  intermediate  queues  re¬ 
quired  to  store  the  data  as  they  move  from  producer  to  consumer  processes. 

This  report  describes  the  Durra  application  debugger/monitor,  a  program  that 
works  in  conjunction  with  the  Durra  runtime  software  to  help  the  developer  lo¬ 
cate  errors  and/or  performance  bottlenecks  in  a  Durra  application. 


1.  Introduction  to  Durra 

1.1.  The  Durra  Language  and  Method 


Durra  [3, 1 , 4]  is  a  language  designed  to  support  the  construction  of  distributed  applica¬ 
tions  using  concurrent,  coarse-grained  tasks  running  on  networks  of  heterogeneous 
processors.  An  application  written  in  Durra  selects  and  reuses  task  descriptions  and 
type  declarations  stored  in  a  library.  The  application  describes  the  tasks  to  be  instan¬ 
tiated  and  executed  as  concurrent  processes,  the  types  of  data  to  be  exchanged  by  the 
processes,  and  the  intermediate  queues  required  to  store  the  data  as  they  move  from 
producer  to  consumer  processes. 

Because  tasks  are  the  primary  building  blocks,  we  refer  to  Durra  as  a  task-level  descrip¬ 
tion  language.  We  use  the  term  description  language  rather  than  programming 
language  to  emphasize  that  a  Durra  application  is  not  translated  into  object  code  in  an 
executable  (conventional)  machine  language.  Instead,  a  Durra  application  is  a  descrip¬ 
tion  of  the  structure  and  behavior  of  a  logical  machine  that  is  to  be  synthesized  into 
resource  allocation  and  scheduling  directives,  which  are  then  interpreted  by  a  combi¬ 
nation  of  software,  firmware,  and  hardware  in  each  of  the  processors  and  buffers  of  a 
heterogeneous  machine.  This  is  the  translation  process  depicted  in  Figure  1. 

There  are  three  distinct  phases  in  the  process  of  developing  an  application  using  Durra: 
the  creation  of  a  library  of  tasks,  the  creation  of  an  application  using  library  tasks,  and 
the  execution  of  the  application. 

During  the  first  phase,  the  developer  writes  descriptions  of  the  component  tasks.  A  task 
description  specifies  some  set  of  properties  of  the  task  implementation,  including  the 
ports  through  which  a  task  communicates  with  other  tasks,  the  types  of  data  it  produces 
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Status  and  Task  requests 
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Figure  1 :  Compilation  of  an  Application  Description 


or  consumes,  and  other  miscellaneous  attributes  of  the  implementation.  For  a  given 

task,  there  may  be  many  implementations,  differing  in  programming  language  (e.g.,  C  or 

assembly  language),  processor  type  (e.g..  Motorola  68020  or  IBM  1401),  performance  • 

characteristics,  or  other  attributes.  For  each  implementation  of  a  task,  a  description 

must  be  written  in  Durra,  compiled,  and  entered  in  the  library. 

During  the  second  phase,  the  user  writes  an  application  description.  Syntactically,  an 
application  description  is  a  single  task  description  that  can  be  stored  in  the  library  as  a 
new  task,  allowing  for  the  writing  of  hierarchical  application  descriptions.  At  this  level  the 
developer  specifies  such  things  as  the  queues  connecting  individual  ports,  required  data 
transformations,  and  potential  reconfigurations  (changes  in  the  topology  of  the 
application).  Compiling  the  application  description  generates  a  set  of  commands,  or  in¬ 
structions,  about  resource  allocation  and  scheduling  to  be  interpreted  by  the  Durra  ex- 
ecutive  (see  Section  1 .2).  * 

During  the  last  phase,  the  executive  loads  the  task  implementations  (i.e.,  programs  cor¬ 
responding  to  the  component  tasks)  onto  the  processors  and  issues  the  appropriate 
commands  to  execute  the  programs. 
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1.2.  The  Durra  Runtime  Environment 


This  section  provides  a  summary  of  the  Durra  runtime  environment  sufficient  for  the  pur¬ 
pose  of  understanding  the  Durra  application  debugger/monitor’s  relationship  to  the  other 
components  of  the  environment.  For  a  more  detailed  description  of  the  the  runtime  envi¬ 
ronment,  see  [2,  4]. 


Figure  2:  The  Durra  Runtime  Environment 


There  are  two  active  components  of  the  minimal  Durra  runtime  environment:  the  appli¬ 
cation  tasks  and  the  Durra  executives.  Figure  2  shows  the  relationship  between  these 
components.  The  executives  can  run  in  master  or  server  mode.  There  is  one  server 
executive  on  each  processor  in  the  configuration  and  it  is  responsible  for  starting  all 
tasks  assigned  to  that  processor.  There  is  one  master  executive  for  the  entire  network 
and  it  is  responsible  for  telling  the  server(s)  which  tasks  to  start,  establishing  commum 
cation  links,  and  controlling  the  execution  of  the  application.  The  executives  implement 
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the  predefined  tasks  (broadcast,  merge,  and  deal)  described  in  [3].  The  executives’ 
specific  actions  are  prescribed  by  a  file  containing  instructions  generated  by  the  Durra 
compiler. 

Once  its  description  has  been  compiled  as  described  in  Section  1 .1 ,  an  application  can 
be  executed  by  performing  the  following  operations: 

1. Load  the  task  implementations  into  system-defined  locations  on  the 
processors  where  they  will  run. 

2.  Start  an  instance  of  the  Durra  executive  on  each  processor.  All  but  one  of 
these  executives  runs  in  server  mode.  The  remaining  executive  runs  in 
master  mode.  The  master  executive  reads  instruction  file  and  initiates  ap¬ 
plication  execution. 
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2.  The  Durra  Application  Debugger/Monitor 

Just  as  a  software  developer  using  a  traditional  high-level  programming  language  re¬ 
quires  a  symbolic  debugger  to  efficiently  isolate  problems  in  his  implementation,  so  a 
Durra  application  developer  will  need  automated  assistance  to  isolate  bugs,  tune  perfor¬ 
mance,  and  control  the  execution  of  the  application.  The  application  debugger/monitor 
(hereafter  referred  to  as  the  monitor,  for  brevity)  addresses  this  requirement. 

Durra  applications  are  potentially  very  complex.  The  Durra  developer  may  face  dif¬ 
ficulties  in  debugging  and  tuning  his  application  that  the  traditional  software  developer 
need  not  consider,  such  as  Yibuted  concurrent  processes,  heterogeneous  processor 
architectures,  mixed-language  programming,  dynamic  reconfiguration,  etc.  The  fact  that 
Durra  hides  the  details  of  these  complications  from  the  developer  is  an  advantage  during 
development  but  an  impediment  during  testing.  At  the  testing  stage,  access  to  the  infor¬ 
mation  about  the  application  state  that  is  encapsulated  in  the  executive,  as  well  as  about 
the  state  of  the  individual  programs  which  make  up  the  Durra  application,  is  useful. 

The  monitor  provides  this  information  at  two  levels,  the  application  level  and  the  source 
level.  The  primary  focus  of  the  monitor  is  at  the  application  level.  Here  the  monitor 
provides  the  abstracted  Durra  view  of  the  world,  where  the  individual  tasks  are  treated 
as  black  boxes  connected  to  each  other  through  Durra  ports  and  queues.  The  user  can 
examine  executive-internal  data,  insert  break  points  on  Durra  communication  interfaces, 
change  task  attributes,  and  do  other  miscellaneous  operations.  See  Chapter  3  for  de¬ 
tails. 

Obviously,  it  is  also  necessary  to  debug  an  application  at  the  source  level.  In  a  mixed- 
language,  mixed-architecture  environment,  it  is  not  feasible  or  desirable  for  Durra  to  pro¬ 
vide  a  source-level  debugging  capability.  Instead,  the  monitor  provides  a  simple  mecha¬ 
nism  for  allowing  the  developer  to  use  existing  source-level  debuggers,  tools  which  are 
widely  available  and  with  which  the  developer  is  already  familiar. 

The  Durra  application  developer  will  also  be  concerned  with  tuning  the  performance  of 
this  application.  Often  it  is  difficult  to  isolate  a  performance  bottleneck  in  one  part  of  the 
application  or  another.  With  this  in  mind,  the  monitor  provides  a  tracking  facility  to  moni¬ 
tor  the  flow  of  data  through  the  Durra  queues.  Given  this  information,  the  developer  may 
be  able  to  identify  the  task  causing  the  problem  and  take  corrective  actions,  such  as 
moving  the  task  to  a  faster  processor  or  re-implementing  the  task  to  improve  its  effi¬ 
ciency. 

Finally,  the  monitor  provides  the  developer  with  the  means  to  control  the  execution  of  the 
application,  e.g.,  stepping  through  the  execution,  one  data  transmission  at  a  time,  rather 
than  allowing  the  application  to  run  freely.  Such  control  is  especially  useful  for  applica¬ 
tions  with  many  specified  reconfigurations,  because  the  reconfigurations  may  be  trig¬ 
gered  by  conditions  which  are  difficult  and/or  time-consuming  to  simulate  in  testing 
mode.  The  monitor  allows  the  user  to  trigger  the  reconfiguration  whether  or  not  the  trig¬ 
ger  condition  has  been  satisfied. 
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3.  Implementation  of  the  Application 
Debugger/Monitor 

The  monitor  is  an  optional  component  of  the  Durra  runtime  environment.  The  user  may 
invoke  it  independently  at  any  time  during  the  execution  of  a  Durra  application,  in  which 
case  it  can  run  on  any  networked  processor  where  its  executable  image  resides.  Alter¬ 
natively,  assuming  the  environment  supports  the  X  Window  System  [6],  the  monitor  may 
be  activated  as  part  of  the  runtime  environment  start-up  procedure  (via  an  optional  argu¬ 
ment  to  the  executive  command  line),  in  which  case  it  will  run  on  the  same  processor  as 
the  executive.  The  X  support  is  required  in  the  latter  case  because  a  dedicated  window 
must  handle  the  monitor’s  user  interface.  Durra:  A  Task-Level  Description  Language 
User's  Manual  [5]  (hereafter  referred  to  as  the  Durra  User's  Manual)  describes  in  detail 
the  start-up  process  in  the  Unix  environment. 
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As  shown  in  Figure  3,  the  monitor  exchanges  information  with  the  master  executive 
through  a  remote  procedure  call  (rpc)  interface,  just  as  Durra  application  tasks  do.  How¬ 
ever,  the  monitor  has  its  own  distinct  set  of  rpcs. 

The  principal  processing  loop  of  the  Durra  executive  scans  for  incoming  communications 
from  all  Durra  tasks,  including  the  monitor  if  it  has  been  activated.  The  only  monitor  rpcs 
the  executive  sees  at  this  level  are  lnlt_Monltor  and  Interrupt;  the  former  call  occurs 
when  the  monitor  starts  up,  the  latter  when  the  user  types  ctrl-C  at  the  keyboard  in  order 
to  interrupt  execution  of  the  application.  On  acceptance  of  either  call,  the  executive 
transfers  control  to  an  alternate  processing  loop,  one  in  which  only  calls  from  the  monitor 
are  accepted.  This  causes  all  application  tasks  to  block  on  their  ensuing  rpcs  to  the 
executive.  At  this  point  the  monitor  prompts  for  commands  (see  Chapter  4)  and  proc¬ 
esses  them,  continuing  until  the  command  go  is  issued,  causing  return  of  control  to  the 
main  processing  loop. 

While  the  executive  processes  communications  from  application  tasks,  the  monitor  waits 
for  input  from  either  the  executive  or  the  keyboard.  If  the  monitor  user  has  requested  it, 
the  executive  sends  the  monitor  messages  indicating  the  progress  of  the  execution.  On 
an  interrupt  from  the  keyboard,  control  is  returned  to  the  monitor  as  described  above.  If 
the  interrupt  is  received  while  messages  from  the  executive  are  being  processed,  then 
the  message  processing  is  completed  before  the  interrupt  is  recognized. 

The  quit  command  causes  the  monitor  to  terminate.  It  can  be  restarted  at  any  time 
while  the  executive  is  active. 

To  illustrate  the  use  of  the  monitor,  we  will  use  a  small  Durra  application.  The  example 
application  in  Figure  4  consists  of  two  type  definitions,  a  data  source  task  with  one  out¬ 
put  port,  two  data  sink  tasks,  each  with  one  input  port,  and  an  instance  of  the  predefined 
task  broadcast,  which  transmits  data  received  from  the  source  task  to  each  of  the  sink 
tasks. 


a  --  Application  Structure 


type  byte  is  size  8; 

type  string  is  array  of  byte; 

b  --  Type  Declarations 

task  taska 
ports 

outl:  out  string; 
attributes 

processor  =  vax; 
implementation  *  "source_task" ; 
end  taska; 

task  taskb 
ports 

ini:  in  string; 
attributes 

processor  =  sun; 
implementation  =  "sink_task" ; 
end  taskb; 

task  taskc 
ports 

ini:  in  string; 
attributes 

processor  =  vax; 
implementation  =  "sink_task"; 
end  taskc; 


c  --  Task  Descriptions 

task  main 

structure 

process  pi:  task  taska; 

p2 :  task  taskb; 
p3 :  task  taskc; 
pb:  task  broadcast 

ports  ini:  in  string; 

outl,  out2 :  out  string; 
end  broadcast; 

queues  qlb[10]:  pi. outl  »  pb.inl; 

qb2[10]:  pb.outl  »  p2.ini; 

qb3(10]:  pb.out2  »  p3.ini; 

end  main; 

d  --  Application  Description 
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Figure  4:  Durra  Application  Example 
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4.  Application  Debugger/Monitor  Commands 

The  Durra  application  debugger/monitor  is  an  interactive  process  which  communicates 
with  the  Durra  executive  at  runtime  to  provide  information  about  and  control  over  the 
progress  of  the  application. 

There  are  two  ways  to  start  the  monitor  in  the  Unix  environment.  To  start  the  monitor 
when  the  application  begins  executing,  use  an  optional  flag  to  the  dexec  command  (this 
requires  X  Window  System  support  from  the  environment).  To  start  the  monitor  after  an 
application  has  begun  executing,  use  the  dmonitor  command.  The  details  of  each 
method  are  described  in  the  Durra  User's  Manual. 

Commands  to  the  monitor  may  be  entered  from  the  keyboard  or  from  a  file  (or  files) 
specified  by  the  user.  Commands  and  keywords  may  be  abbreviated  to  the  shortest 
non-ambiguous  initial  substring;  identifiers  must  always  be  complete.  This  section  de¬ 
scribes  the  commands  recognized  by  the  monitor. 

The  following  notation  is  used  in  the  monitor  command  descriptions: 

command  or  keyword 

identifier  or  literal-value 

' ' [  a  I  b  ]  '  '  means  choice  of  a  or  b 

"{  a  )''  means  that  a  is  an  optional  argument 

The  character  is  a  wildcard  symbol  implying  all  possible  values  that  make  sense  in 
the  context.  In  the  context  of  an  expected  port,  queue,  task,  or  type  name,  the  ex¬ 
pands  to  all  such  names  in  the  application  currently  running.  In  the  context  of  an  ex¬ 
pected  rpc-name,  the  expands  to  all  the  Durra  interface  call  names.  If  an  optional 
argument  is  omitted,  the  effect  is  the  same  as  if  the  value  of  the  argument  were 

Excerpts  from  a  sample  monitoring  session  on  the  previously  described  example  Durra 
application  appear  throughout  the  following  discussion.  In  all  excerpts,  lines  beginning 
with  the  prompt  monitor>  represent  commands  and  all  other  lines  represent  monitor 
responses. 


4.1.  Go,  Quit,  and  Ctrl-C  Commands 

This  section  describes  commands  which  control  the  interaction  between  the  monitor  and 
executive. 

go  {  duration  > 

The  go  command  tells  the  executive  to  continue  processing  the  application  for  a  speci¬ 
fied  amount  of  time  (in  seconds)  before  prompting  the  users  for  more  commands.  If  no 
duration  is  specified,  the  application  runs  indefinitely.  The  user  can  always  regain  control 
by  typing  ctrl-C  to  interrupt  the  monitor. 
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quit 

The  quit  command  ends  the  monitoring  session. 


ctrl-C 

A  ctrl-C  interrupts  the  application  and  prompts  the  user  for  a  monitor  command. 


4.2.  Watch  and  Break  Commands 

This  section  describes  commands  which  allow  the  user  to  follow  the  flow  of  data  through 
an  application  and  interrupt  the  application  at  any  point  of  communication  with  the  Durra 
runtime. 


dpbreak  {  [  port-name  |  '  ]  {  [  rpc-name  I  "*"  ]  >  } 

dpwatch  {  [  port-name  |  ]  {  [  rpc-name  |  ]  >  > 

dqbreak  {  [  queue-name  |  '  ]  {  t  rpc-name  I  "*"  ]  >  > 

dqwatch  {  [  queue-name  |  ]  {  [  rpc-name  \  ]  }  > 

dtbreak  {  [  task-name  |  "*"  ]  {  [  rpc-name  |  '  '  ]  }  } 

dtwatch  {  [  task-name  |  '  ]  {  [  rpc-name  |  } 

The  above  commands  are  used  to  delete  break  points  or  watch  points,  which  are  de¬ 
fined  below. 


pbreak  {  [  port-name  \  ]  {  [  rpc-name  |  } 

pwatch  {  [  port-name  |  ]  {  [  rpc-name  |  "*"]>> 

qbreak  {  [  queue-name  \  ]  {  [  rpc-name  |  ]  }  > 

qwatch  {  [  queue-name  |  ]  {  [  rpc-name  \  ]  >  } 

tbreak  {  t  task-name  |  "*"  ]  {  [  rpc-name  |  ]  }  } 

twatch  {  [  task-name  |  "*"  ]  {  [  rpc-name  |  "*"  ]  }  } 

The  above  commands  are  used  to  set  break  points  and  watch  points,  where  a  break  (or 

watch)  point  is  defined  as  a  state  in  the  application  execution  sequence  at  which  a  speci¬ 
fied  Durra  object  (port,  queue,  or  task)  is  referenced  by  one  of  a  specified  set  of  task 
interface  rpcs.  When  a  break  point  is  set  and  the  application  reaches  the  specified  inter¬ 
face  call  on  (from)  the  specified  object,  the  application  is  interrupted  and  control  passes 
to  the  monitor  so  that  the  user  may  issue  further  commands.  When  a  watch  point  is  set, 
the  monitor  informs  the  user  that  the  watch  point  has  been  passed  but  the  application 
continues  to  run. 

In  the  following  excerpt,  the  user  sets  a  watch  point  on  the  port  main. pi  .out l  for  all 
rpcs  and  then  issues  the  go  command,  causing  the  application  to  resume  running.  The 
monitor  displays  a  message  each  time  an  rpc  targeted  at  main.pl.outi  occurs.  In 
this  case,  only  send_Port  calls  are  occurring  on  that  port.  The  messages  continue 
until  there  is  no  more  activity  on  that  port  or  until  the  user  interrupts  from  the  keyboard. 
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monitor>  pwatch  main.pl.outl  * 
monitor>  go 

Watch  at  port  MAIN. PI .0UT1,  RPC 
Watch  at  port  MAIN.P1.0UT1,  RPC 
Watch  at  port  MAIN . PI .OUTI,  RPC 
Watch  at  port  MAIN . PI . OUT1 ,  RPC 
Watch  at  port  MAIN. PI .OUTI,  RPC 
Watch  at  port  MAIN. PI .OUT1,  RPC 
Watch  at  port  MAIN. PI .0UT1,  RPC 


SEND_PORT 
SEND_PORT 
SEND_PORT 
SEND_PORT 
SEND_PORT 
SEND_PORT 
SEND  PORT 


Next,  the  user  removes  all  port  watch  points  and  sets  a  queue  watch  point  on  queue 
main .  qb2  for  all  rpcs.  The  queue  has  an  associated  producer  port,  main  .pbi .  outi, 
and  an  associated  consumer  port,  main. p2 .ini.  The  occurrence  of  an  rpc  on  either 
port,  then,  causes  a  message  to  be  displayed  by  the  monitor.  (If  the  port  watch  point 
had  not  been  removed,  port  and  queue  watch  point  responses  would  have  been 
interleaved).  When  a  Send_Port  or  Get_Port  occurs,  the  monitor  describes  the 
queue  state.  Below,  when  the  Send_Port  occurs,  the  consumer  task  is  already  waiting 
for  the  data  and  so  the  data  is  immediately  transmitted,  bypassing  the  queue.  The  con¬ 
sumer  then  issues  another  Get_Port  before  any  more  data  has  been  sent  and  so  it  is 
blocked,  waiting  for  data  to  arrive. 

monitor>  dpwatch  *  * 
monitor>  qwatch  main.qb2  * 
monitor>  go 

Watch  at  queue  MAIN . QB2 ,  RPC  =  TEST_OUTPUT_PORT,  on  port 
MAIN. PBI. OUTI 

Watch  at  queue  MAIN.QB2,  RPC  =  SEND_PORT,  issued  by  task  MAIN. PBI 
Some  task  already  waiting,  data  sent  immediately 
Watch  at  queue  MAIN.QB2,  RPC  =  GET_PORT,  issued  by  task  MAIN.P2 
Queue  is  empty,  receiver  is  blocked 
Watch  at  queue  MAIN . QB2 ,  RPC  =  TEST_OUTPUT_PORT,  on  port  MAIN. PBI. 
OUTI 


Now  the  user  removes  all  queue  watch  points  and  sets  a  watch  point  on  the  task 
main  .pbi  for  all  rpcs.  Each  time  an  rpc  originates  from  that  task,  a  message  identifying 
the  rpc  (and  the  target  port,  where  appropriate,)  is  displayed.  In  this  case  main  .pbi  is 
an  instance  of  the  predefined  broadcast  task,  and  so  the  rpcs  are  only  simulated. 


monitor> 

monitor> 

monitor> 

Observed 

Observed 

Observed 

Observed 

Observed 

Observed 

Observed 


dqwatch  *  * 
twatch  main. pbi  * 
go 

task  MAIN. PBI  doing  TEST_INPUT_PORT  at  port  MAIN . PBI . INI 
task  MAIN. PBI  doing  TEST_OUTPUT_PORT  at  port  MAIN . PBI . OUTI 
task  MAIN. PBI  doing  TEST_OUTPUT_PORT  at  port  MAIN. PBI .OUT2 
task  MAIN. PBI  doing  GET_PORT  at  port  MAIN. PBI . INI 
task  MAIN . PBI  doing  SEND_PORT  at  port  MAIN. PBI .OUTI 
task  MAIN. PBI  doing  SEND_PORT  at  port  MAIN.PB1 .OUT2 
task  MAIN . PBI  doing  SAFE 
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Break  points  work  exactly  like  watch  points,  except  that  when  a  break  point  is  reached 
the  application  is  interrupted  and  the  user  has  the  opportunity  to  enter  more  commands. 
In  the  following  excerpt,  the  user  removes  the  watch  points  previously  set  and  then  sets 
a  break  point  on  any  task  doing  a  Get_Port.  At  each  occurrence  the  user  responds 
with  the  go  command  and  the  application  continues  to  the  next  instance  of  Get_Port. 
The  task  break  point  is  then  removed  and  a  queue  break  point  set.  The  effect  of  the 
queue  break  point  is  analogous  to  that  of  the  task  break  point. 


monitor>  dtwatch  *  * 
monitor>  tbreak  *  get_port 
monitor>  go 

Break  at  task  MAIN.PB1  doing  GET_PORT  at  port  MAIN.PB1.INI 
monitor>  go 

Break  at  task  MAIN . P3  doing  GET_PORT  at  port  MAIN.P3.INI 
monitor>  go 

Break  at  task  MAIN.P2  doing  GET_PORT  at  port  MAIN.P2.INI 
monitor>  dtbreak  *  * 
monitor>  qbreak  main.qlb  * 
monitor>  go 

Break  at  queue  MAIN . Q1B,  RPC  -  SEND_PORT,  issued  by  task  MAIN. PI 
Some  task  already  waiting,  data  sent  immediately 
monitor>  go 

Break  at  queue  MAIN . Q1B,  RPC  -  TEST_INPUT_PORT,  on  port  MAIN.PB1.INI 
monitor>  go 

Break  at  queue  MAIN . Q1B,  RPC  -  GET_PORT,  issued  by  task  MAIN.PB1 


4.3.  Kill,  Stop,  and  Resume  Commands 

This  section  describes  commands  used  to  control  the  execution  state  of  an  application’s 
component  tasks. 

kill  [  task-name  |  '  ] 

stop  [  task-name  \  '  ] 

resume  [  task-name  |  ] 

These  commands  are  used  to  terminate,  pause,  or  continue  execution  of  a  task  at  the 
operating  system  level.  As  noted  previously,  break  points  interrupt  a  task  at  the  point  of 
some  interface  call  to  the  executive.  It  may  happen,  though,  that  the  user  wishes  to 
interrupt  an  application  task  that  executes  for  long  periods  of  time  without  resorting  to  an 
interface  call;  on  such  occasions  the  stop  and  resume  commands  are  useful.  The  kill 
command  might  be  used  to  simulate  the  occurrence  of  unexpected  task  failure  for  sys¬ 
tem  testing  purposes. 
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4.4.  Show  and  Track  Commands 


This  section  describes  commands  which  allow  the  user  to  see  information  about  the  ap¬ 
plication  currently  executing. 


show  attributes  [ task-name  |  "*"] 

The  show  attributes  command  displays  the  attributes  of  the  specified  task(s).  In  the 
example  following  we  see  the  attributes  of  task  main  .p2. 

monitor>  show  attributes  main.p2 
ATTRIBUTES  of  task  MAIN . P2 

implementation  =  sink_task 
processor  =  SUN 
source  =  taskb.durra .TREE 
xdisplay  =  :0.0 


show  configuration 

The  show  configuration  command  displays  the  name  of  the  current  configuration  and 
all  configurations  which  can  be  reached  directly  from  the  current  level. 


show  port  [  port-name  |  ] 

show  queue  [  queue-name  |  ] 

show  task  [  task-name  \  ] 

show  type  [  type-name  \  ' ] 


These  commands  display  information  the  Durra  executive  knows  about  the  application’s 
Durra  ports,  queues,  tasks,  and  types.  Each  of  the  following  fragments  demonstrates 
the  results  of  one  of  these  commands.  Additional  information  is  displayed  when  the  situ¬ 
ation  warrants.  For  instance,  if  any  break  points  or  watch  points  have  been  set  on  the 
ports,  queues,  or  tasks  in  question,  then  that  information  will  be  shown. 


monitor>  show  port  main. p3.ini 


NAME  -  MAIN.P3.INI 
ID 

CONF IGURAT ION_LE VEL 
DATA_TYPE 
ASSOCIATE  D_QUEUE 
STATUS 

PORT  DIRECTION 


-  2 

=  MAIN 
=  STRING 
-  MAIN . QB3 
=  CONFIGURED 
=  IN 


The  following  example  shows  that  the  receiving  tasks  are  waiting  for  data  at  queues 
main . qb2  and  main.qb3,  but  neither  sender  nor  receiver  is  waiting  at  queue 
main . qib  (since  no  “waiting_client”  field  is  displayed).  Queue  main.qlb  has  an  up¬ 
per  bound  of  10  messages  and  currently  contains  three.  The  results  of  any  active  track 
command  would  also  be  displayed  here. 


CMU/SEI-89-TR-32 


15 


i 


monitor>  show  queue  * 
NAME  -  MAIN . Q1B 
ID 

CONF IGURAT ION_LEVEL 
SOURCE_PORT 
DESTINATION_PORT 
BOUND 

ELEMENT_COUNT 

STATUS 

NAME  =  MAIN . QB2 
ID 

CONF I GURAT I ON_LE VE L 
SOURCE_PORT 
DESTINATION_PORT 
BOUND 

ELEMENT_COUNT 

WAITING_CLIENT 

STATUS 

NAME  =  MAIN . QB3 
ID 

CONF IGURAT ION_LE VEL 
SOURCE_PORT 
DESTINATION_PORT 
BOUND 

ELEMENT_COUNT 

WAITING_CLIENT 

STATUS 


1 

MAIN 

MAIN .PI. OUT1 
MAIN . PB1 . INI 
10 
3 

CONFIGURED 

2 

MAIN 

MAIN . PB1 . OUT1 
MAIN . P2 . INI 
10 
0 

MAIN . P2 
CONFIGURED 

3 

MAIN 

MAIN . PB1 . OUT2 
MAIN . P3 . INI 
10 
0 

MAIN . P3 
CONFIGURED 


Some  explanation  of  the  task  fields  may  be  required.  The  fields  Mailbox  and 
Server_mailbox  refer  to  communications  channels  from  the  master  executive  to  the 
task  and  from  the  master  executive  to  the  server  executive  that  started  the  task,  respec¬ 
tively.  p id  and  xpid  are  the  process  IDs  of  the  task  and  any  associated  xterm  [6]. 
Signal_Pending  indicates  whether  or  not  a  signal  has  been  received  from  this  task 
during  a  reconfiguration.  Time_Out  is  the  time  in  seconds  that  the  task  has  to  get  to  a 
quiescent  state  [7]  for  reconfiguration  before  it  is  terminated.  Quiesce_Status  in¬ 
dicates  whether  or  not  the  task  is  in  a  reconfigurable  state. 


monitor>  show  task  main.pl 


NAME  =  MAIN. PI 
KIND 
ID 

CONF IGURAT I ON_LE VEL  = 

MAILBOX 

SERVER_MAILBOX 

PID 

XPID 

PORTS 

S I GNAL_P ENDING 

TIME_OUT 

STATUS 

QUIESCE  STATUS 


USER 

3 

MAIN 

9 

5 

10099 

0 

MAIN. PI . OUT1 
FALSE 
20 

CONFIGURED 
RUN ABLE 


The  lower_bound  and  upper_bound  in  the  following  type  description  refer  to  bounds 
on  the  size  of  the  type;  since  both  have  a  value  of  8 ,  type  byte  is  fixed-length,  8  bits. 
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monitor>  show  type  byte 
NAME  =  BYTE 
KIND 
ID 

LOWER_BOUND 
UPPER  BOUND 


SIZE_TYPE 

2 

8 

8 


show  state 

The  show  queue  and  show  task  commands  described  above  may  provide  more  infor¬ 
mation  than  is  desired.  For  example,  if  at  some  point  during  application  execution  one 
wished  to  know  how  many  messages  were  in  each  queue,  one  could  display  all  queue 
information  using  the  command  show  queue  *  and  then  browse  through  it  looking  for 
the  relevant  numbers.  Instead,  we  provide  the  show  state  command,  the  purpose  of 
which  is  to  display  a  concise  picture  of  the  state  of  the  tasks  and  queues  comprising  the 
application.  Below  is  a  sample;  the  user  may  assume  that  any  task  not  shown  is  not 
blocked  currently  and  any  queue  not  shown  is  empty. 

monitor>  show  state 

Task  MAIN . P2  (consumer)  blocked  at  queue  MAIN.QB2 
Queue  MAIN . Q1B  contains  1  messages,  bound  =  1 


show  track  [queue-name  |  ] 

The  show  track  command  displays  the  results  of  a  track  command  on  the  specified 
queue(s).  The  tracking  operation  records  the  elapsed  time  since  tracking  began,  the 
number  of  data  items  that  have  passed  through  the  queue  during  that  time,  the  average 
time  a  data  item  spent  in  the  queue,  and  the  number  of  times  the  sending  and  receiving 
tasks  blocked  while  attempting  to  write  to  or  read  from  the  queue.  In  the  following  ex¬ 
cerpt,  we  see  the  user  request  a  track  operation  on  all  queues.  The  application  starts 
and  runs  until  interrupted  from  the  keyboard.  The  results  of  the  tracking  operation  after 
90  seconds  show  that  120  data  elements  passed  through  each  queue.  The  receiving 
task  connected  to  main.qb2  had  to  wait  every  time;  hence  the  average  time  a  datum 
spent  in  the  queue  was  zero,  since  each  was  sent  directly  out  when  it  arrived.  In  the 
other  two  queues,  neither  sender  nor  receiver  ever  blocked,  and  so  the  average  wait 
time  in  the  queue  is  non-zero. 
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monitor>  track  * 
monitor>  go 


{keyboard  interrupt) 
monitor>  show  track  * 
NAME  =  MAIN . Q1B 

ELAP SED_TRACK_T IME 
D AT A_F  LO W_COUNT 
AVG_T IME_IN_QUEUE 
SENDER_BLOCKED 
RECEIVER_BLOCKED 
NAME  =  MAIN.QB2 

ELAP SED_TRACK_T IME 
DATA_FLOW_COUNT 
AVG_T  IME_IN__QUEUE 
SENDER_BLOCKED 
RECEIVER_BLOCKED 
NAME  =  MAIN . QB3 

ELAP SED_TRACK_T IME 
DATA_FLOW_COUNT 
AVG_T IME_IN_QUEUE 
SENDER_BLOCKED 
RECEIVER  BLOCKED 


»  90.0  seconds 

-  120 

“  1.666E-3  seconds 

0  times 
0  times 

»  90.0  seconds 

-  120 

=  0.000E+0  seconds 

0  times 
120  times 


=  90.0  seconds 

-  120 

-  8.333E-5  seconds 

0  times 
0  times 


track  [ queue-name  |  "*"] 
dtrack  [ queue-name  \  "*"] 

Beginning  at  the  time  it  is  issued,  the  track  command  initiates  the  collection  of  data 
through  the  specified  queue(s).  Partial  results  of  the  tracking  can  be  displayed  at  any 
time  with  the  show  track  command.  Tracking  continues  until  the  dtrack  command  is 
issued. 


4.5.  Read,  Echo,  and  Silent  Commands 

This  section  describes  commands  which  affect  the  manner  in  which  the  monitor  commu¬ 
nicates  with  its  user. 

read  command_file 

The  read  command  specifies  a  command  file  from  which  monitor  commands  should  be 
read.  Command  files  may  contain  nested  read  commands.  When  the  monitor  finishes 
reading  the  commands  in  the  file,  command  processing  continues  from  the  scope  in 
which  the  read  command  was  invoked,  unless  the  file  contains  a  quit  command,  in 
which  case  the  monitor  is  terminated  as  usual. 

echo 

The  echo  command  requests  that  monitor  commands  be  displayed  as  they  are  proc¬ 
essed.  This  is  the  default  when  commands  are  entered  interactively.  If  the  commands 
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are  being  read  by  the  monitor  from  a  file,  th  default  is  silent,  or  no  display,  except  when 
the  file  is  being  read  via  a  nested  read  command,  in  which  case  the  echoing  status  is 
inherited  from  the  calling  environment. 

silent 

The  silent  command  suppresses  the  display  of  monitor  commands  that  are  read  from 
command  files.  This  is  the  default  (unless  echo  is  inherited  from  an  enclosing  file).  This 
command  has  no  effect  when  issued  interactively. 


4.6.  Set  Commands 

This  section  describes  the  commands  used  to  change  certain  values  maintained  by  the 
Durra  runtime. 

set  attribute  task-name  attribute-name  attribute-value 

The  set  attribute  command  gives  the  specified  task  an  arbitrarily-named  attribute  with 
an  arbitrary  string  value.  Attributes  controlling  process  execution  location  and  display 
location  do  not  take  effect  until  the  next  time  the  process  is  started.  Some  attribute 
names  are  reserved  because  they  have  special  meaning  to  the  Durra  runtime;  see  the 
Durra  User’s  Manual  tor  details. 

set  bound  [ queue-name  \ 
positive-integer-value] 

The  set  bound  command  changes  the  maximum  size  of  the  specified  queue.  The 
change  takes  effect  immediately.  If  a  task  has  been  blocked  attempting  to  write  to  the 
queue,  and  the  new  bound  is  larger  than  the  old  bound,  the  task  will  be  unblocked. 


4.7.  Miscellaneous  Commands 

This  section  describes  monitor  commands  which  don’t  fit  into  any  of  the  preceding  cate¬ 
gories. 

debug  task-name  {  debugger-string  } 

The  debug  command  requests  that  the  specified  task  be  run  under  control  of  a  source- 
level  debugger.  The  command  must  be  issued  before  the  task  is  started  or  it  will  have 
no  effect.  The  optional  debugger-string  provides  a  way  to  specify  some  debugger  in¬ 
vocation  other  than  the  environment-specified  default  (e.g.,  special  arguments  to  the  de- 
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fault  debugger  or  a  different  debugger  altogether).  Since  a  separate  terminal  interface  is 
required  for  each  debugger  activated,  this  feature  is  only  available  when  the  environ¬ 
ment  supports  the  X  Window  System.  Instead  of  starting  the  task  directly,  the  Durra 
executive  starts  an  xterm  and  runs  the  specified  debugger  in  it,  giving  it  the  task  name 
as  an  argument. 

help 

The  help  command  displays  an  online  help  screen  which  lists  the  monitor  commands, 
reconfigure  { configuration Jabel} 

The  reconfigure  command  causes  a  reconfiguration  to  the  specified  configuration  level 
to  occur,  regardless  of  the  state  of  any  specified  trigger  condition.  The  configuration 
label  is  optional  if  there  is  only  one  possible  reconfiguration. 

The  command  has  no  effect  when  the  specified  configuration  does  not  exist  or  is  un¬ 
reachable  from  the  current  configuration.  The  command  also  fails  when  another  recon¬ 
figuration  is  pending,  i.e.,  the  executive  has  initiated  a  configuration  change  but  has  not 
yet  completed  it  (for  instance,  when  waiting  for  a  task  to  get  to  a  quiescent  state).  Only 
one  reconfiguration  may  be  in  progress  at  any  point  in  time. 


References 


[1]  M.R.  Barbacci,  C.B.  Weinstock,  and  J.M.  Wing. 

Programming  at  the  Processor-Memory-Switch  Level. 

In  Proceedings  of  the  10th  International  Conference  on  Software  Engineering. 
Singapore,  April,  1988. 

[2]  M.R.  Barbacci,  D.L.  Doubleday,  and  C.B.  Weinstock. 

The  Durra  Runtime  Environment. 

Technical  Report  CMU/SEI-88-TR-18  (DTIC:  ADA1 99480),  Software  Engineering 
Institute,  Carnegie  Mellon  University,  July,  1988. 

[3]  M.R.  Barbacci  and  J.M.  Wing. 

Durra:  A  Task-Level  Description  Language  Reference  Manual  (Version  2). 

Technical  Report  CMU/SEI-89-TR-34,  Software  Engineering  Institute,  Carnegie 
Mellon  University,  September,  1989. 

[4]  M.R.  Barbacci,  D.L.  Doubleday,  C.B.  Weinstock,  and  J.M.  Wing. 

Developing  Applications  for  Heterogeneous  Machine  Networks:  The  Durra  Envi¬ 
ronment. 

Computing  Systems  2(1),  March,  1989. 

[5]  M.R.  Barbacci,  D.L.  Doubleday,  and  C.B.  Weinstock. 

Durra:  A  Task-Level  Description  Language  User’s  Manual. 

Technical  Report  CMU/SEI-89-TR-33,  Software  Engineering  Institute,  Carnegie 
Mellon  University,  September,  1989. 

[6]  R.W.  Scheifler  and  J.  Gettys. 

The  X  Window  System. 

ACM  Transactions  on  Graphics  5(2):79-1 09,  April,  1 986. 

[7]  C.B.  Weinstock. 

Performance  and  Reliability  Enhancement  of  the  Durra  Runtime  Environment. 

Technical  Report  CMU/SEI-89-TR-8  (DTIC:  ADA207445),  Software  Engineering 
Institute,  Carnegie  Mellon  University,  February,  1989. 


CMU/SEI-89-TR-32 


21 


Index 


*  11 

Broadcast  13 

Ctrl-C  11,12 

Debug  19 
Dexec  1 1 
Dmonitor  1 1 
Dpbreak  1 2 
Dpwatch  1 2 
Dqbreak  1 2 
Dqwatch  1 2 
Dtbreak  12 
□track  18 
Dtwatch  12 

Echo  18,  19 

Go  8,  11,  12,  14 

Help  20 

Interrupt  11 

Kill  14 

Pbreak  1 2 
Pwatch  1 2 

Qbreak  1 2 
Quiescent  16,20 
Quit  8,  12,  18 
Qwatch  1 2 

Read  18, 19 
Reconfigure  20 
Resume  14 

Set  attribute  1 9 
Set  bound  19 
Show  attributes  15 
Show  configuration  15 
Show  port  1 5 
Show  queue  15,17 
Show  state  1 7 
Show  task  15,17 
Show  track  17,18 
Show  type  15 
Silent  19 
Stop  14 


Tbreak  1 2 
Track  15,17,18 
Twatch  1 2 

Xterm  16 


CMU/SEI-89-TR-32 


23 


UNLIMITED.  UNn.AssiriF-n _ 

SECURITY  CLASSIFICATION  OF  This  PAGE 


REPORT  DOCUMENTATION  PAGE 


},  report  security  CLASSIFICATION 

UNCLASSIFIED 


2*.  SECURITY  CLASSIFICATION  AUTHORITY 

N/A  _ 


2b  OE  C  LASS  I  FICATION/OOWNGRAOlNG  SCHEDULE 

N/A  _ 


4  PERFORMING  ORGANIZATION  REPORT  NUM6EHISI 


1b.  RESTRICTIVE  MARKINGS 

NONE 


3.  OISTRI6UTION/A  VAILABILITY  OF  REPORT 

APPROVED  FOR  PUBLIC  RELEASE 
DISTRIBUTION  UNLIMITED 


5.  MONITORING  ORGANIZATION  REPORT  NUMBER(S) 


CMU/SEI-89-TR-32 


6c  AOORESS  (City.  State  ana  ZIP  Code  I 

CARNEGIE  MELLON  UNIVERSITY 
PITTSBURGH,  PA  15213 


_ 1  ESD-TR-89-43 _ 


b.  OFFICE  SYMBOL  7*.  NAME  OF  MONITORING  ORGANIZATION 
(If  applicable  I 


SEI  JOINT  PROGRAM  OFFICE 


ADDRESS  (City.  State  and  ZIP  Code) 

ESD/XRS 1 

HANSCOM  AIR  FORCE  BASE,  MA  01731 


84.  NAME  OF  FUNOING/SPONSORING 
ORGANIZATION 


SEI  JOINT  PROGRAM  OFFICE 


8c.  AOORESS  (City.  State  and  ZIP  Code) 

CARNEGIE  MELLON  UNIVERSITY 
SOFTWARE  ENGINEERING  INSTITUTE  JPO 
PTTTCRTn?<CH  PA  IS?  11 


11.  TITLE  ( Include  Security  Classification! 


80.  OFFICE  SYMBOL  9.  PROCUREMENT  INSTRUMENT  IDENTIFICATION  NUMBER 
(If  applicable) 

SEI  JPO  F1962885C0003 


10.  SOURCE  OE  FUNDING  NOS. 


PROGRAM 
ELEMENT  NO 


WORK.  UNIT 
NO. 


12.  PERSONAL  AUTHOR(S) 

Dennis  L.  Doubleday 

13*.  type  of  report 

FINAL 

1  13b.  time  COVERED  1 

I  FROM  TO  j 

1  14  OATE  OF  REPORT  (Yr  .  Mo..  Day) 

\  September,  1989 

15.  PAGE  COUNT 

16.  supplementary  notation 


COSAT  I  CODES 


18  SUBJECT  TERMS  ( Continue  on  reverse  if  necessary  and  identify  by  block  number) 


19.  ABSTRACT  (Continue  on  reverse  if  necessary  and  identify  by  block  number) 

Durra  is  a  language  designed  to  support  the  construction  of  distributed  applications 
using  concurrent,  coarse-grained  tasks  running  on  networks  of  heterogeneous  processors. 
An  application  written  in  Durra  describes  the  tasks  to  be  instantiated  and  executed 
as  concurrent  processes,  the  types  of  data  to  be  exchanged  by  the  processes,  and  the 
intermediate  queues  required  to  store  the  data  as  they  move  from  producer  to  consumer 
processes . 

This  report  describes  the  Durra  application  debugger/monitor ,  a  program  that  works  in 
conjunction  with  the  Durra  runtime  software  to  help  the  developer  located  errors  and/or 
performance  bottlenecks  in  a  Durra  application. 


20  OISTRIBUTION/AVAILABILITY  of  abstract 
UNCLASSIFIEO/UNLIMITE  o  12  SAME  AS  RPT  LJ  otic  USERS  u 


22*  NAME  OF  RESPONSIBLE  INDIVIDUAL 

KARL  SHINGLER 


DO  FORM  1473,  83  APR 


21.  ABSTRACT  SECURITY  CLASSIFICATION 

UNCLASSIFIED,  UNLIMITED 


22b  TELEPHONE  NUMBER 

(Include  Area  Code i 

(412)  268-7630 


EDITION  OF  1  JAN  73  IS  OBSOLETE 


72c  OFFICE  SYMBOL 

SEI  JPO 


UNLIMITED,  UNCLASSIFIED 

SECURITY  CLASSIFICATION  OF  THIS  PAG: 


